{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "89cf2628",
   "metadata": {},
   "source": [
    "# Short Circuit Example\n",
    "\n",
    "This notebook contains an example of a short circuit calculation using `power-grid-model`.\n",
    "The following points are covered\n",
    " * Construction of the model\n",
    " * Run short circuit calculation, and its relevant function arguments\n",
    "\n",
    "This notebook skips most of the common features across all calculations of power-grid-model like updating model, batch calculations and error handling.\n",
    "\n",
    "It serves as an example of how to use the Python API. For detailed API documentation, refer to\n",
    "[Python API reference](../api_reference/python-api-reference.md)\n",
    "and [Native Data Interface](../advanced_documentation/native-data-interface.md).\n",
    "\n",
    "\n",
    "## Example Network\n",
    "\n",
    "We use a simple network with 3 nodes, 1 source, 3 lines, and 2 loads. As shown below:\n",
    "\n",
    "```\n",
    " -----------------------line_8---------------\n",
    " |                                          |\n",
    "node_1 ---line_3--- node_2 ----line_5---- node_6 ---- fault_11\n",
    " |                    |                     |\n",
    "source_10          sym_load_4           sym_load_7\n",
    "```\n",
    "\n",
    "The 3 nodes are connected in a triangular way by 3 lines."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "ae11dc9a",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-08-03T08:29:18.753481900Z",
     "start_time": "2023-08-03T08:29:17.530737800Z"
    }
   },
   "outputs": [],
   "source": [
    "# some basic imports\n",
    "import numpy as np\n",
    "\n",
    "from power_grid_model import (\n",
    "    AttributeType,\n",
    "    CalculationMethod,\n",
    "    CalculationType,\n",
    "    ComponentType,\n",
    "    DatasetType,\n",
    "    FaultPhase,\n",
    "    FaultType,\n",
    "    LoadGenType,\n",
    "    PowerGridModel,\n",
    "    ShortCircuitVoltageScaling,\n",
    "    initialize_array,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f983cef7",
   "metadata": {},
   "source": [
    "## Input Dataset\n",
    "\n",
    "Please refer to [Components](../user_manual/components.md) for detailed explanation of all component types and their input/output attributes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "6f008736",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-08-03T08:29:18.763488Z",
     "start_time": "2023-08-03T08:29:18.758492200Z"
    }
   },
   "outputs": [],
   "source": [
    "# node\n",
    "node = initialize_array(DatasetType.input, ComponentType.node, 3)\n",
    "node[AttributeType.id] = np.array([1, 2, 6])\n",
    "node[AttributeType.u_rated] = [10.5e3, 10.5e3, 10.5e3]\n",
    "\n",
    "# line\n",
    "line = initialize_array(DatasetType.input, ComponentType.line, 3)\n",
    "line[AttributeType.id] = [3, 5, 8]\n",
    "line[AttributeType.from_node] = [1, 2, 1]\n",
    "line[AttributeType.to_node] = [2, 6, 6]\n",
    "line[AttributeType.from_status] = [1, 1, 1]\n",
    "line[AttributeType.to_status] = [1, 1, 1]\n",
    "line[AttributeType.r1] = [0.25, 0.25, 0.25]\n",
    "line[AttributeType.x1] = [0.2, 0.2, 0.2]\n",
    "line[AttributeType.c1] = [10e-6, 10e-6, 10e-6]\n",
    "line[AttributeType.tan1] = [0.0, 0.0, 0.0]\n",
    "line[AttributeType.i_n] = [1000, 1000, 1000]\n",
    "\n",
    "# load\n",
    "sym_load = initialize_array(DatasetType.input, ComponentType.sym_load, 2)\n",
    "sym_load[AttributeType.id] = [4, 7]\n",
    "sym_load[AttributeType.node] = [2, 6]\n",
    "sym_load[AttributeType.status] = [1, 1]\n",
    "sym_load[AttributeType.type] = [LoadGenType.const_power, LoadGenType.const_power]\n",
    "sym_load[AttributeType.p_specified] = [20e6, 10e6]\n",
    "sym_load[AttributeType.q_specified] = [5e6, 2e6]\n",
    "\n",
    "# source\n",
    "source = initialize_array(DatasetType.input, ComponentType.source, 1)\n",
    "source[AttributeType.id] = [10]\n",
    "source[AttributeType.node] = [1]\n",
    "source[AttributeType.status] = [1]\n",
    "source[AttributeType.u_ref] = [1.0]\n",
    "\n",
    "# fault\n",
    "fault = initialize_array(DatasetType.input, ComponentType.fault, 1)\n",
    "fault[AttributeType.id] = [11]\n",
    "fault[AttributeType.status] = [1]\n",
    "fault[AttributeType.fault_object] = [6]\n",
    "fault[AttributeType.fault_type] = [FaultType.three_phase]\n",
    "fault[AttributeType.fault_phase] = [FaultPhase.abc]\n",
    "fault[AttributeType.r_f] = [0.1]\n",
    "fault[AttributeType.x_f] = [0.1]\n",
    "\n",
    "# all\n",
    "input_data = {\n",
    "    ComponentType.node: node,\n",
    "    ComponentType.line: line,\n",
    "    ComponentType.sym_load: sym_load,\n",
    "    ComponentType.source: source,\n",
    "    ComponentType.fault: fault,\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "039711c7",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "\n",
    "**Note: During a single calculation, all types of faults should be similar.**"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "68a38330",
   "metadata": {},
   "source": [
    "## Validation (optional)\n",
    "For efficiency reasons, most of the data is not explicitly validated in the power grid model. However, in most cases, a power flow calculation will fail/crash if the data is invalid. Often with a low level error message that is hard to relate to the original objects. Therfore, it is recommended to always validate your data before constructing a PowerGridModel instance.\n",
    "\n",
    "The simplest and most effective way to validate your data is by using `assert_valid_input_data()` which will throw an error if it encounters any invalid data. See [Validation Examples](./Validation%20Examples.ipynb) for more detailed information on the validation functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "40509eaf",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-08-03T08:29:18.811133300Z",
     "start_time": "2023-08-03T08:29:18.764503700Z"
    }
   },
   "outputs": [],
   "source": [
    "from power_grid_model.validation import assert_valid_input_data\n",
    "\n",
    "assert_valid_input_data(input_data=input_data, calculation_type=CalculationType.short_circuit)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "afae0224",
   "metadata": {},
   "source": [
    "## Construction\n",
    "\n",
    "The construction of the model is just calling the constructor of `PowerGridModel`.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "7ef134e9",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-08-03T08:29:18.811133300Z",
     "start_time": "2023-08-03T08:29:18.804083800Z"
    }
   },
   "outputs": [],
   "source": [
    "model = PowerGridModel(input_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e3605c3e",
   "metadata": {},
   "source": [
    "## One-time Short circuit Calculation\n",
    "\n",
    "You can call the method `calculate_short_circuit` to do a one-time calculation based on the current network data in the model.\n",
    "\n",
    "The short circuit calculation has the following settings as arguments:\n",
    " * calculation_method: CalculationMethod.iec60909,\n",
    " * short_circuit_voltage_scaling: ShortCircuitVoltageScaling.maximum\n",
    "\n",
    "Currently, there is only one calculation method for short-circuit which calculates as per IEC 60909. The `short_circuit_voltage_scaling` is a scaling of source voltages based on the nominal node voltages.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "44c2de63",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-08-03T08:29:18.823792200Z",
     "start_time": "2023-08-03T08:29:18.811133300Z"
    },
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "output_data = model.calculate_short_circuit(\n",
    "    calculation_method=CalculationMethod.iec60909, short_circuit_voltage_scaling=ShortCircuitVoltageScaling.maximum\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d08aaf45",
   "metadata": {},
   "source": [
    "### Result Dataset\n",
    "\n",
    "The short circuit calculation results are always asymmetric. This means we cannot convert them to dataframes\n",
    "\n",
    "The following code prints some result attributs of nodes, faults, and lines in arrays.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "a581a36e",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-08-03T08:29:18.895579800Z",
     "start_time": "2023-08-03T08:29:18.827799800Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "------fault result: id------\n",
      "[11]\n",
      "------fault result: i_f------\n",
      "[[18404.40044631 18404.40044631 18404.40044631]]\n",
      "\n",
      "------node result: id------\n",
      "[1 2 6]\n",
      "------node result: u_pu------\n",
      "[[1.07539348 1.07539348 1.07539348]\n",
      " [0.75227027 0.75227027 0.75227027]\n",
      " [0.42934657 0.42934657 0.42934657]]\n",
      "\n",
      "------line result: id------\n",
      "[3 5 8]\n",
      "------line result: u_pu------\n",
      "[[ 6119.72533835  6119.72533835  6119.72533835]\n",
      " [ 6131.26794632  6131.26794632  6131.26794632]\n",
      " [12255.79671336 12255.79671336 12255.79671336]]\n"
     ]
    }
   ],
   "source": [
    "print(\"\\n------fault result: id------\")\n",
    "print(output_data[ComponentType.fault][AttributeType.id])\n",
    "print(\"------fault result: i_f------\")\n",
    "print(output_data[ComponentType.fault][AttributeType.i_f])\n",
    "\n",
    "print(\"\\n------node result: id------\")\n",
    "print(output_data[ComponentType.node][AttributeType.id])\n",
    "print(\"------node result: u_pu------\")\n",
    "print(output_data[ComponentType.node][AttributeType.u_pu])\n",
    "\n",
    "print(\"\\n------line result: id------\")\n",
    "print(output_data[ComponentType.line][AttributeType.id])\n",
    "print(\"------line result: u_pu------\")\n",
    "print(output_data[ComponentType.line][AttributeType.i_from])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1884ebd4",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Batch Calculations\n",
    "\n",
    "The batch calculations are mentioned in detail in the [Power Flow Example](./Power%20Flow%20Example.ipynb). Short circuit batch calculations are carried out in similar way."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "power-grid-model",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.14.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}